﻿namespace Sgr.Organizations
{
    /// <summary>
    /// 提供用户数据的抽象。实现应负责从不同源（本地 DB / 钉钉 / 企业微信 / WPS 云）获取用户信息。
    /// 约定：返回物化集合时使用 <see cref="IReadOnlyList{T}"/>；大数据量场景可使用流式 <see cref="IAsyncEnumerable{T}"/>.
    /// 单项查询找不到时返回 null。
    /// </summary>
    public interface IUserProvider
    {
        ///// <summary>
        ///// 获取全部用户（一次性物化，适用于小数据集或需要 Count/索引 的场景）。
        ///// 永远不返回 null；找不到用户返回空集合。
        ///// </summary>
        //Task<IReadOnlyList<UserInfo>> GetAllAsync(CancellationToken ct = default);

        ///// <summary>
        ///// 按外部平台 Id 与源（例如 "DingTalk"/"WeCom"/"Wps"）查询，找不到返回 null。
        ///// </summary>
        //Task<UserInfo?> GetByExternalIdAsync(string externalId, string source, CancellationToken ct = default);

        /// <summary>
        /// 按 权限名称 获取用户列表
        /// </summary>
        Task<IReadOnlyList<UserInfo>> GetByPermissionAsync(string orgId, string permission, int max, CancellationToken ct = default);

        /// <summary>
        /// 获取部门主管
        /// </summary>
        /// <param name="orgId"></param>
        /// <param name="deptId"></param>
        /// <param name="max"></param>
        /// <param name="ct"></param>
        /// <returns></returns>
        Task<IReadOnlyList<UserInfo>> GetDeptManagerUserAsync(string orgId, string deptId, int max, CancellationToken ct = default);

        /// <summary>
        /// 检查用户是否为指定部门的主管
        /// </summary>
        /// <param name="orgId"></param>
        /// <param name="deptId"></param>
        /// <param name="userId"></param>
        /// <param name="ct"></param>
        /// <returns></returns>
        Task<bool> CheckUserIsDeptManager(string orgId, string deptId, string userId, CancellationToken ct = default);

        /// <summary>
        /// 按内部用户 Id 查询，找不到返回 null。
        /// </summary>
        Task<UserInfo?> GetByIdAsync(long orgId, long userId, CancellationToken ct = default);

        /// <summary>
        /// 按手机号查询，若存在多个会返回首个匹配（实现可自定义策略），找不到返回 null。
        /// </summary>
        Task<UserInfo?> GetByMobileAsync(string mobile, CancellationToken ct = default);

        /// <summary>
        /// 按邮箱查询，找不到返回 null。
        /// </summary>
        Task<UserInfo?> GetByEmailAsync(string email, CancellationToken ct = default);
    }
}